feat(mcp): replace the reference number tools with update_record - #511

Why

Akshay asked in Project AI why reference numbers got their own add and remove tools instead of a patch tool. We had ported #452's shape as-is. One record-update tool is the better design: it matches set_party_role and set_custom_field, and it cuts the tool count.

What changes

• update_record replaces add_reference_numbers and remove_reference_numbers (feat(mcp): add opt-in reference number tools #510). Those were opt-in and never served in production.
• Inputs: entity_type + entity_id, then ref_numbers: { add, remove } (containers, shipments, tracking requests) and tags: { add, remove } (shipments only).
• Tier C with confirms: "destructive_only". A call that only adds writes at once. A call that removes anything returns a preview and needs approval, through elicitation or a token. This is the same kit path set_party_role uses.
• Terminal49 replaces whole lists on PATCH, so the tool reads the lists, merges the change, writes them and reads them back. concurrent_change_detected and the unreadable-list guard carry over from feat(mcp): add opt-in reference number tools #510.
• It is in the default operations toolset, so production serves it on deploy without an env change. The reference_numbers toolset is removed.
• The store submission files, docs and counts are updated: 31 default tools, 34 total. The Claude directory listing needs update_record added in the developer portal.

Testing

• npx vp test run in packages/mcp: 69 files, 1014 tests pass. New tests cover add-only writes, unchanged calls, the removal preview and token, stale previews, shipment tags with reference numbers, unreadable lists, 422 noop, and input validation.
• Lint, format, the agent-trust guard and the OpenAPI checks pass.
• Staging QA follows before merge.

🤖 Generated with Claude Code

^{Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.}

Confidence Score: 4/5

The PR appears safe to merge, with non-blocking feedback to restore read-back failure tests.

Findings

1.  Read-back failure tests were dropped ▶

### Issue 1
packages/mcp/src/tools/update-record.test.ts:98-100
The replacement tests cover only a successful read-back. The deleted tests also checked a changed list, a failed second GET, and an unreadable second response. Restore those cases for `update_record`, including shipment `tags`. They protect the distinction between `concurrent_change_detected: true` and an unknown result with `read_back_note`, so future changes cannot silently report the wrong result after a successful write.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[update_record] --> B[Read requested lists]
  B --> C{Lists readable?}
  C -->|No| D[Return unreadable_list]
  C -->|Yes| E{Any change?}
  E -->|No| F[Return unchanged]
  E -->|Yes| G{Removes a stored value?}
  G -->|No| J[PATCH merged lists]
  G -->|Yes| H[Show preview and ask for approval]
  H --> I[Check approval and current lists]
  I -->|Valid and unchanged| J
  I -->|Changed| H
  J --> K[Read lists back and report result]

_{Reviews (1) · Last reviewed commit: "feat(mcp): replace the reference number ..." · Reviewed by Greptile}